<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Input/Output</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter 1. Boost.JSON">
<link rel="up" href="../index.html" title="Chapter 1. Boost.JSON">
<link rel="prev" href="allocators/uses_allocator.html" title="Uses-allocator construction">
<link rel="next" href="examples.html" title="Examples">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="allocators/uses_allocator.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="json.input_output"></a><a class="link" href="input_output.html" title="Input/Output">Input/Output</a>
</h2></div></div></div>
<p>
      The library provides parsing and serialization algorithms to transform JSON
      to and from the <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
      container as needed. This is accomplished through free functions and classes,
      described as follows.
    </p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="json.input_output.parsing"></a><a class="link" href="input_output.html#json.input_output.parsing" title="Parsing">Parsing</a>
</h3></div></div></div>
<p>
        Parsing is the process where a serialized JSON is validated and decomposed
        into elements. The library provides these functions and types to assist with
        parsing:
      </p>
<div class="table">
<a name="json.input_output.parsing.parsing_functions_and_types"></a><p class="title"><b>Table 1.8. Parsing Functions and Types</b></p>
<div class="table-contents"><table class="table" summary="Parsing Functions and Types">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__basic_parser.html" title="basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A SAX push parser implementation which converts a serialized JSON
                  into a series of member function calls to a user provided handler.
                  This allows custom behaviors to be implemented for representing
                  the document in memory.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__parse_options.html" title="parse_options"><code class="computeroutput"><span class="identifier">parse_options</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A structure used to select which extensions are enabled during
                  parsing.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__parse.html" title="parse"><code class="computeroutput"><span class="identifier">parse</span></code></a>
                </p>
              </td>
<td>
                <p>
                  Parse a string containing a complete serialized JSON, and return
                  a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__parser.html" title="parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A stateful DOM parser object which may be used to efficiently parse
                  a series of JSONs each contained in a single contiguous character
                  buffer, returning each result as a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__stream_parser.html" title="stream_parser"><code class="computeroutput"><span class="identifier">stream_parser</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A stateful DOM parser object which may be used to efficiently parse
                  a series of JSONs incrementally, returning each result as a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__value_stack.html" title="value_stack"><code class="computeroutput"><span class="identifier">value_stack</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A low level building block used for efficiently building a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>.
                  The parsers use this internally, and users may use it to adapt
                  foreign parsers to produce this library's containers.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        The <a class="link" href="ref/boost__json__parse.html" title="parse"><code class="computeroutput"><span class="identifier">parse</span></code></a>
        function offers a simple interface for converting a serialized JSON text
        to a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        in a single function call. This overload uses exceptions to indicate errors:
      </p>
<pre class="programlisting"><span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,4,5]"</span> <span class="special">);</span>
</pre>
<p>
        Alternatively, an <a class="link" href="ref/boost__json__error_code.html" title="error_code"><code class="computeroutput"><span class="identifier">error_code</span></code></a> can be used:
      </p>
<pre class="programlisting"><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
<span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,4,5]"</span><span class="special">,</span> <span class="identifier">ec</span> <span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">)</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ec</span><span class="special">.</span><span class="identifier">message</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
</pre>
<p>
        Even when using error codes, exceptions thrown from the underlying <a class="link" href="ref/boost__json__memory_resource.html" title="memory_resource"><code class="computeroutput"><span class="identifier">memory_resource</span></code></a>
        are still possible:
      </p>
<pre class="programlisting"><span class="keyword">try</span>
<span class="special">{</span>
    <span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
    <span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,4,5]"</span><span class="special">,</span> <span class="identifier">ec</span> <span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">)</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ec</span><span class="special">.</span><span class="identifier">message</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        The <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        returned in the preceding examples use the default memory resource. The following
        code uses a <a class="link" href="ref/boost__json__monotonic_resource.html" title="monotonic_resource"><code class="computeroutput"><span class="identifier">monotonic_resource</span></code></a>, which results
        in faster parsing. <code class="computeroutput"><span class="identifier">jv</span></code> is
        marked <code class="computeroutput"><span class="keyword">const</span></code> to prevent subsequent
        modification, because containers using a monotonic resource waste memory
        when mutated.
      </p>
<pre class="programlisting"><span class="special">{</span>
    <span class="identifier">monotonic_resource</span> <span class="identifier">mr</span><span class="special">;</span>

    <span class="identifier">value</span> <span class="keyword">const</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,4,5]"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">mr</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
<h5>
<a name="json.input_output.parsing.h0"></a>
        <span class="phrase"><a name="json.input_output.parsing.non_standard_json"></a></span><a class="link" href="input_output.html#json.input_output.parsing.non_standard_json">Non-Standard
        JSON</a>
      </h5>
<p>
        Unless otherwise specified, the parser in this library is strict. It recognizes
        only valid, standard JSON. The parser can be configured to allow certain
        non-standard extensions by filling in a <a class="link" href="ref/boost__json__parse_options.html" title="parse_options"><code class="computeroutput"><span class="identifier">parse_options</span></code></a> structure and passing
        it by value. By default all extensions are disabled:
      </p>
<pre class="programlisting"><span class="identifier">parse_options</span> <span class="identifier">opt</span><span class="special">;</span>                                  <span class="comment">// all extensions default to off</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_comments</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                          <span class="comment">// permit C and C++ style comments to appear in whitespace</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_trailing_commas</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                   <span class="comment">// allow an additional trailing comma in object and array element lists</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_invalid_utf8</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                      <span class="comment">// skip utf-8 validation of keys and strings</span>

<span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,] // comment "</span><span class="special">,</span> <span class="identifier">storage_ptr</span><span class="special">(),</span> <span class="identifier">opt</span> <span class="special">);</span>
</pre>
<p>
        When building with C++20 or later, the use of <a href="https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers" target="_top">designated
        initializers</a> with <a class="link" href="ref/boost__json__parse_options.html" title="parse_options"><code class="computeroutput"><span class="identifier">parse_options</span></code></a> is possible:
      </p>
<pre class="programlisting"><span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span> <span class="string">"[1,2,3,] // comment "</span><span class="special">,</span> <span class="identifier">storage_ptr</span><span class="special">(),</span>
    <span class="special">{</span>
        <span class="special">.</span><span class="identifier">allow_comments</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">,</span>             <span class="comment">// permit C and C++ style comments to appear in whitespace</span>
        <span class="special">.</span><span class="identifier">allow_trailing_commas</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">,</span>      <span class="comment">// allow a trailing comma in object and array lists</span>
        <span class="special">.</span><span class="identifier">allow_invalid_utf8</span> <span class="special">=</span> <span class="keyword">true</span>          <span class="comment">// skip utf-8 validation of keys and strings</span>
    <span class="special">});</span>
</pre>
<h5>
<a name="json.input_output.parsing.h1"></a>
        <span class="phrase"><a name="json.input_output.parsing.parser"></a></span><a class="link" href="input_output.html#json.input_output.parsing.parser">Parser</a>
      </h5>
<p>
        Instances of <a class="link" href="ref/boost__json__parser.html" title="parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>
        and <a class="link" href="ref/boost__json__stream_parser.html" title="stream_parser"><code class="computeroutput"><span class="identifier">stream_parser</span></code></a>
        offer functionality beyond what is available when using the <a class="link" href="ref/boost__json__parse.html" title="parse"><code class="computeroutput"><span class="identifier">parse</span></code></a> free functions:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            More control over memory
          </li>
<li class="listitem">
            Streaming API, parse input JSON incrementally
          </li>
<li class="listitem">
            Improved performance when parsing multiple JSONs
          </li>
<li class="listitem">
            Ignore non-JSON content after the end of a JSON
          </li>
</ul></div>
<p>
        The parser implementation uses temporary storage space to accumulate values
        during parsing. When using the <a class="link" href="ref/boost__json__parse.html" title="parse"><code class="computeroutput"><span class="identifier">parse</span></code></a> free functions, this storage
        is allocated and freed in each call. However, by declaring an instance of
        <a class="link" href="ref/boost__json__parser.html" title="parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>
        or <a class="link" href="ref/boost__json__stream_parser.html" title="stream_parser"><code class="computeroutput"><span class="identifier">stream_parser</span></code></a>,
        this temporary storage can be reused when parsing more than one JSON, reducing
        the total number of dynamic memory allocations.
      </p>
<p>
        To use the <a class="link" href="ref/boost__json__parser.html" title="parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>,
        declare an instance. Then call <a class="link" href="ref/boost__json__parser/write.html" title="parser::write"><code class="computeroutput"><span class="identifier">write</span></code></a> once with the buffer containing
        representing the input JSON. Finally, call <a class="link" href="ref/boost__json__parser/release.html" title="parser::release"><code class="computeroutput"><span class="identifier">release</span></code></a> to take ownership of the
        resulting <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        upon success. This example persists the parser instance in a class member
        to reuse across calls:
      </p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">connection</span>
<span class="special">{</span>
    <span class="identifier">parser</span> <span class="identifier">p_</span><span class="special">;</span>                                      <span class="comment">// persistent data member</span>

<span class="keyword">public</span><span class="special">:</span>
    <span class="keyword">void</span> <span class="identifier">do_read</span><span class="special">(</span> <span class="identifier">string_view</span> <span class="identifier">s</span> <span class="special">)</span>                   <span class="comment">// called for each complete message from the network</span>
    <span class="special">{</span>
        <span class="identifier">p_</span><span class="special">.</span><span class="identifier">reset</span><span class="special">();</span>                                 <span class="comment">// start parsing a new JSON using the default resource</span>
        <span class="identifier">p_</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span> <span class="identifier">s</span> <span class="special">);</span>                              <span class="comment">// parse the buffer, using exceptions to indicate error</span>
        <span class="identifier">do_rpc</span><span class="special">(</span> <span class="identifier">p_</span><span class="special">.</span><span class="identifier">release</span><span class="special">()</span> <span class="special">);</span>                     <span class="comment">// process the command</span>
    <span class="special">}</span>

    <span class="keyword">void</span> <span class="identifier">do_rpc</span><span class="special">(</span> <span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">);</span>
<span class="special">};</span>
</pre>
<p>
        Sometimes a protocol may have a JSON text followed by data that is in a different
        format or specification. The JSON portion can still be parsed by using the
        function <a class="link" href="ref/boost__json__parser/write_some.html" title="parser::write_some"><code class="computeroutput"><span class="identifier">write_some</span></code></a>. Upon success, the return
        value will indicate the number of characters consumed from the input, which
        will exclude the non-JSON characters:
      </p>
<pre class="programlisting"><span class="identifier">stream_parser</span> <span class="identifier">p</span><span class="special">;</span>
<span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
<span class="identifier">string_view</span> <span class="identifier">s</span> <span class="special">=</span> <span class="string">"[1,2,3] %HOME%"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">write_some</span><span class="special">(</span> <span class="identifier">s</span><span class="special">,</span> <span class="identifier">ec</span> <span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">ec</span> <span class="special">&amp;&amp;</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">done</span><span class="special">()</span> <span class="special">&amp;&amp;</span> <span class="identifier">n</span> <span class="special">==</span> <span class="number">8</span> <span class="special">);</span>
<span class="identifier">s</span> <span class="special">=</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">substr</span><span class="special">(</span> <span class="identifier">n</span> <span class="special">);</span>
<span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">release</span><span class="special">();</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">s</span> <span class="special">==</span> <span class="string">"%HOME%"</span> <span class="special">);</span>
</pre>
<p>
        The parser instance may be constructed with parse options which allow some
        non-standard JSON extensions to be recognized:
      </p>
<pre class="programlisting"><span class="identifier">parse_options</span> <span class="identifier">opt</span><span class="special">;</span>                                  <span class="comment">// All extensions default to off</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_comments</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                          <span class="comment">// Permit C and C++ style comments to appear in whitespace</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_trailing_commas</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                   <span class="comment">// Allow an additional trailing comma in object and array element lists</span>
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">allow_invalid_utf8</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>                      <span class="comment">// Skip utf-8 validation of keys and strings</span>
<span class="identifier">stream_parser</span> <span class="identifier">p</span><span class="special">(</span> <span class="identifier">storage_ptr</span><span class="special">(),</span> <span class="identifier">opt</span> <span class="special">);</span>              <span class="comment">// The stream_parser will use the options</span>
</pre>
<h5>
<a name="json.input_output.parsing.h2"></a>
        <span class="phrase"><a name="json.input_output.parsing.streaming_parser"></a></span><a class="link" href="input_output.html#json.input_output.parsing.streaming_parser">Streaming
        Parser</a>
      </h5>
<p>
        The <a class="link" href="ref/boost__json__stream_parser.html" title="stream_parser"><code class="computeroutput"><span class="identifier">stream_parser</span></code></a>
        implements a <a href="https://en.wikipedia.org/wiki/Online_algorithm" target="_top"><span class="emphasis"><em>streaming
        algorithm</em></span></a>; it allows incremental processing of large JSON
        inputs using one or more contiguous character buffers. The entire input JSON
        does not need to be loaded into memory at once. A network server can use
        the streaming interface to process incoming JSON in fixed-size amounts, providing
        these benefits:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            CPU consumption per I/O cycle is bounded
          </li>
<li class="listitem">
            Memory consumption per I/O cycle is bounded
          </li>
<li class="listitem">
            Jitter, unfairness, and latency is reduced
          </li>
<li class="listitem">
            Less total memory is required to process the full input
          </li>
</ul></div>
<p>
        To use the <a class="link" href="ref/boost__json__stream_parser.html" title="stream_parser"><code class="computeroutput"><span class="identifier">stream_parser</span></code></a>, declare an instance.
        Then call <a class="link" href="ref/boost__json__stream_parser/write.html" title="stream_parser::write"><code class="computeroutput"><span class="identifier">write</span></code></a> zero or more times with successive
        buffers representing the input JSON. When there are no more buffers, call
        <a class="link" href="ref/boost__json__stream_parser/finish.html" title="stream_parser::finish"><code class="computeroutput"><span class="identifier">finish</span></code></a>. The function <a class="link" href="ref/boost__json__stream_parser/done.html" title="stream_parser::done"><code class="computeroutput"><span class="identifier">done</span></code></a> returns <code class="computeroutput"><span class="keyword">true</span></code>
        after a successful call to <code class="computeroutput"><span class="identifier">write</span></code>
        or <code class="computeroutput"><span class="identifier">finish</span></code> if parsing is complete.
      </p>
<p>
        In the following example a JSON is parsed from standard input a line at a
        time. Error codes are used instead. The function <a class="link" href="ref/boost__json__stream_parser/finish.html" title="stream_parser::finish"><code class="computeroutput"><span class="identifier">finish</span></code></a> is used to indicate the end
        of the input:
      </p>
<pre class="programlisting"><span class="identifier">value</span> <span class="identifier">read_json</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&amp;</span> <span class="identifier">is</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">stream_parser</span> <span class="identifier">p</span><span class="special">;</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">line</span><span class="special">;</span>
    <span class="keyword">while</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">getline</span><span class="special">(</span> <span class="identifier">is</span><span class="special">,</span> <span class="identifier">line</span> <span class="special">)</span> <span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">p</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span> <span class="identifier">line</span><span class="special">,</span> <span class="identifier">ec</span> <span class="special">);</span>
        <span class="keyword">if</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">)</span>
            <span class="keyword">return</span> <span class="keyword">nullptr</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">finish</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">)</span>
        <span class="keyword">return</span> <span class="keyword">nullptr</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">release</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<h5>
<a name="json.input_output.parsing.h3"></a>
        <span class="phrase"><a name="json.input_output.parsing.controlling_memory"></a></span><a class="link" href="input_output.html#json.input_output.parsing.controlling_memory">Controlling
        Memory</a>
      </h5>
<p>
        After default construction, or after <a class="link" href="ref/boost__json__stream_parser/reset.html" title="stream_parser::reset"><code class="computeroutput"><span class="identifier">reset</span></code></a> is called with no arguments,
        the <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        produced after a successful parse operation uses the default memory resource.
        To use a different memory resource, call <code class="computeroutput"><span class="identifier">reset</span></code>
        with the resource to use. Here we use a <a class="link" href="ref/boost__json__monotonic_resource.html" title="monotonic_resource"><code class="computeroutput"><span class="identifier">monotonic_resource</span></code></a>, which is optimized
        for parsing but not subsequent modification:
      </p>
<pre class="programlisting"><span class="special">{</span>
    <span class="identifier">monotonic_resource</span> <span class="identifier">mr</span><span class="special">;</span>

    <span class="identifier">stream_parser</span> <span class="identifier">p</span><span class="special">;</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">reset</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">mr</span> <span class="special">);</span>                                 <span class="comment">// Use mr for the resulting value</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span> <span class="string">"[1,2,3,4,5]"</span> <span class="special">);</span>                       <span class="comment">// Parse the input JSON</span>
    <span class="identifier">value</span> <span class="keyword">const</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">release</span><span class="special">();</span>                   <span class="comment">// Retrieve the result</span>
    <span class="identifier">assert</span><span class="special">(</span> <span class="special">*</span><span class="identifier">jv</span><span class="special">.</span><span class="identifier">storage</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">mr</span> <span class="special">);</span>                  <span class="comment">// Same memory resource</span>
<span class="special">}</span>
</pre>
<p>
        To achieve performance and memory efficiency, the parser uses a temporary
        storage area to hold intermediate results. This storage is reused when parsing
        more than one JSON, reducing the total number of calls to allocate memory
        and thus improving performance. Upon construction, the memory resource used
        to perform allocations for this temporary storage area may be specified.
        Otherwise, the default memory resource is used. In addition to a memory resource,
        the parser can make use of a caller-owned buffer for temporary storage. This
        can help avoid dynamic allocations for small inputs. The following example
        uses a four kilobyte temporary buffer for the parser, and falls back to the
        default memory resource if needed:
      </p>
<pre class="programlisting"><span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="identifier">temp</span><span class="special">[</span> <span class="number">4096</span> <span class="special">];</span>                                 <span class="comment">// Declare our buffer</span>
<span class="identifier">stream_parser</span> <span class="identifier">p</span><span class="special">(</span>
    <span class="identifier">storage_ptr</span><span class="special">(),</span>                                          <span class="comment">// Default memory resource</span>
    <span class="identifier">parse_options</span><span class="special">{},</span>                                        <span class="comment">// Default parse options (strict parsing)</span>
    <span class="identifier">temp</span><span class="special">);</span>                                                  <span class="comment">// Use our buffer for temporary storage</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="json.input_output.parsing.avoiding_dynamic_allocations"></a><a class="link" href="input_output.html#json.input_output.parsing.avoiding_dynamic_allocations" title="Avoiding Dynamic Allocations">Avoiding
        Dynamic Allocations</a>
</h4></div></div></div>
<p>
          Through careful specification of buffers and memory resources, it is possible
          to eliminate all dynamic allocation completely when parsing JSON, for the
          case where the entire JSON is available in a single character buffer, as
          shown here:
        </p>
<pre class="programlisting"><span class="comment">/*  Parse JSON and invoke the handler

    This function parses the JSON specified in `s`
    and invokes the handler, whose signature must
    be equivalent to:

        void( value const&amp; jv );

    The operation is guaranteed not to perform any
    dynamic memory allocations. However, some
    implementation-defined upper limits on the size
    of the input JSON and the size of the resulting
    value are imposed.

    Upon error, an exception is thrown.
*/</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">Handler</span> <span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">do_rpc</span><span class="special">(</span> <span class="identifier">string_view</span> <span class="identifier">s</span><span class="special">,</span> <span class="identifier">Handler</span><span class="special">&amp;&amp;</span> <span class="identifier">handler</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="identifier">temp</span><span class="special">[</span> <span class="number">4096</span> <span class="special">];</span>                 <span class="comment">// The parser will use this storage for its temporary needs</span>
    <span class="identifier">parser</span> <span class="identifier">p</span><span class="special">(</span>                                   <span class="comment">// Construct a strict parser using the temp buffer and no dynamic memory</span>
        <span class="identifier">get_null_resource</span><span class="special">(),</span>                    <span class="comment">// The null resource never dynamically allocates memory</span>
        <span class="identifier">parse_options</span><span class="special">(),</span>                        <span class="comment">// Default constructed parse options allow only standard JSON</span>
        <span class="identifier">temp</span> <span class="special">);</span>

    <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="identifier">buf</span><span class="special">[</span> <span class="number">16384</span> <span class="special">];</span>                 <span class="comment">// Now we need a buffer to hold the actual JSON values</span>
    <span class="identifier">static_resource</span> <span class="identifier">mr2</span><span class="special">(</span> <span class="identifier">buf</span> <span class="special">);</span>                 <span class="comment">// The static resource is monotonic, using only a caller-provided buffer</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">reset</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">mr2</span> <span class="special">);</span>                            <span class="comment">// Use the static resource for producing the value</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span> <span class="identifier">s</span> <span class="special">);</span>                               <span class="comment">// Parse the entire string we received from the network client</span>

    <span class="comment">// Retrieve the value and invoke the handler with it.</span>
    <span class="comment">// The value will use `buf` for storage. The handler</span>
    <span class="comment">// must not take ownership, since monotonic resources</span>
    <span class="comment">// are inefficient with mutation.</span>
    <span class="identifier">handler</span><span class="special">(</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">release</span><span class="special">()</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
</div>
<h5>
<a name="json.input_output.parsing.h4"></a>
        <span class="phrase"><a name="json.input_output.parsing.custom_parsers"></a></span><a class="link" href="input_output.html#json.input_output.parsing.custom_parsers">Custom
        Parsers</a>
      </h5>
<p>
        Users who wish to implement custom parsing strategies may create their own
        handler to use with an instance of <a class="link" href="ref/boost__json__basic_parser.html" title="basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a>. The handler implements
        the function signatures required by SAX event interface. In this example
        we define the "null" parser, which does nothing with the parsed
        results, to use in the implementation of a function that determines if a
        JSON text is valid.
      </p>
<pre class="programlisting"><span class="comment">/*
    This example verifies that a file contains valid JSON.
*/</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">json</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="comment">// This file must be manually included when</span>
<span class="comment">// using basic_parser to implement a parser.</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">json</span><span class="special">/</span><span class="identifier">basic_parser_impl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>

<span class="preprocessor">#include</span> <span class="string">"file.hpp"</span>

<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">json</span><span class="special">;</span>

<span class="comment">// The null parser discards all the data</span>
<span class="keyword">class</span> <span class="identifier">null_parser</span>
<span class="special">{</span>
    <span class="keyword">struct</span> <span class="identifier">handler</span>
    <span class="special">{</span>
        <span class="keyword">constexpr</span> <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_object_size</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span>
        <span class="keyword">constexpr</span> <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_array_size</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span>
        <span class="keyword">constexpr</span> <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_key_size</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span>
        <span class="keyword">constexpr</span> <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_string_size</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span>

        <span class="keyword">bool</span> <span class="identifier">on_document_begin</span><span class="special">(</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_document_end</span><span class="special">(</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_object_begin</span><span class="special">(</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_object_end</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_array_begin</span><span class="special">(</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_array_end</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_key_part</span><span class="special">(</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_key</span><span class="special">(</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_string_part</span><span class="special">(</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_string</span><span class="special">(</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_number_part</span><span class="special">(</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_int64</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int64_t</span><span class="special">,</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_uint64</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span><span class="special">,</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_double</span><span class="special">(</span> <span class="keyword">double</span><span class="special">,</span> <span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_bool</span><span class="special">(</span> <span class="keyword">bool</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_null</span><span class="special">(</span> <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_comment_part</span><span class="special">(</span><span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
        <span class="keyword">bool</span> <span class="identifier">on_comment</span><span class="special">(</span><span class="identifier">string_view</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&amp;)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span>
    <span class="special">};</span>

    <span class="identifier">basic_parser</span><span class="special">&lt;</span><span class="identifier">handler</span><span class="special">&gt;</span> <span class="identifier">p_</span><span class="special">;</span>

<span class="keyword">public</span><span class="special">:</span>
    <span class="identifier">null_parser</span><span class="special">()</span>
        <span class="special">:</span> <span class="identifier">p_</span><span class="special">(</span><span class="identifier">parse_options</span><span class="special">())</span>
    <span class="special">{</span>
    <span class="special">}</span>

    <span class="special">~</span><span class="identifier">null_parser</span><span class="special">()</span>
    <span class="special">{</span>
    <span class="special">}</span>

    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span>
    <span class="identifier">write</span><span class="special">(</span>
        <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="keyword">auto</span> <span class="keyword">const</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">p_</span><span class="special">.</span><span class="identifier">write_some</span><span class="special">(</span> <span class="keyword">false</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">size</span><span class="special">,</span> <span class="identifier">ec</span> <span class="special">);</span>
        <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">ec</span> <span class="special">&amp;&amp;</span> <span class="identifier">n</span> <span class="special">&lt;</span> <span class="identifier">size</span><span class="special">)</span>
            <span class="identifier">ec</span> <span class="special">=</span> <span class="identifier">error</span><span class="special">::</span><span class="identifier">extra_data</span><span class="special">;</span>
        <span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span>
    <span class="special">}</span>
<span class="special">};</span>

<span class="keyword">bool</span>
<span class="identifier">validate</span><span class="special">(</span> <span class="identifier">string_view</span> <span class="identifier">s</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="comment">// Parse with the null parser and return false on error</span>
    <span class="identifier">null_parser</span> <span class="identifier">p</span><span class="special">;</span>
    <span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
    <span class="identifier">p</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">size</span><span class="special">(),</span> <span class="identifier">ec</span> <span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span> <span class="identifier">ec</span> <span class="special">)</span>
        <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>

    <span class="comment">// The string is valid JSON.</span>
    <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
<span class="special">}</span>

<span class="keyword">int</span>
<span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">**</span> <span class="identifier">argv</span><span class="special">)</span>
<span class="special">{</span>
    <span class="keyword">if</span><span class="special">(</span><span class="identifier">argc</span> <span class="special">!=</span> <span class="number">2</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span>
            <span class="string">"Usage: validate &lt;filename&gt;"</span>
            <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
        <span class="keyword">return</span> <span class="identifier">EXIT_FAILURE</span><span class="special">;</span>
    <span class="special">}</span>

    <span class="keyword">try</span>
    <span class="special">{</span>
        <span class="comment">// Read the file into a string</span>
        <span class="keyword">auto</span> <span class="keyword">const</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">read_file</span><span class="special">(</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">);</span>

        <span class="comment">// See if the string is valid JSON</span>
        <span class="keyword">auto</span> <span class="keyword">const</span> <span class="identifier">valid</span> <span class="special">=</span> <span class="identifier">validate</span><span class="special">(</span> <span class="identifier">s</span> <span class="special">);</span>

        <span class="comment">// Print the result</span>
        <span class="keyword">if</span><span class="special">(</span> <span class="identifier">valid</span> <span class="special">)</span>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="string">" contains a valid JSON\n"</span><span class="special">;</span>
        <span class="keyword">else</span>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="string">" does not contain a valid JSON\n"</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span>
            <span class="string">"Caught exception: "</span>
            <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
        <span class="keyword">return</span> <span class="identifier">EXIT_FAILURE</span><span class="special">;</span>
    <span class="special">}</span>

    <span class="keyword">return</span> <span class="identifier">EXIT_SUCCESS</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="json.input_output.serializing"></a><a class="link" href="input_output.html#json.input_output.serializing" title="Serializing">Serializing</a>
</h3></div></div></div>
<p>
        Serialization is the process where a JSON document represented in memory
        by a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        is turned into a sequence of characters. The library provides the following
        free functions and types for serialization:
      </p>
<div class="table">
<a name="json.input_output.serializing.serialization_functions_and_type"></a><p class="title"><b>Table 1.9. Serialization Functions and Types</b></p>
<div class="table-contents"><table class="table" summary="Serialization Functions and Types">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__operator_lt__lt_.html" title="operator&lt;&lt;"><code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code></a>
                </p>
              </td>
<td>
                <p>
                  Serialize a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>, <a class="link" href="ref/boost__json__array.html" title="array"><code class="computeroutput"><span class="identifier">array</span></code></a>, <a class="link" href="ref/boost__json__object.html" title="object"><code class="computeroutput"><span class="identifier">object</span></code></a>, or <a class="link" href="ref/boost__json__string.html" title="string"><code class="computeroutput"><span class="identifier">string</span></code></a> to a <a href="https://en.cppreference.com/w/cpp/io/basic_ostream" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code></a>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__serialize.html" title="serialize"><code class="computeroutput"><span class="identifier">serialize</span></code></a>
                </p>
              </td>
<td>
                <p>
                  Return a <a href="https://en.cppreference.com/w/cpp/string/basic_string" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code></a> representing a
                  serialized <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>, <a class="link" href="ref/boost__json__array.html" title="array"><code class="computeroutput"><span class="identifier">array</span></code></a>, <a class="link" href="ref/boost__json__object.html" title="object"><code class="computeroutput"><span class="identifier">object</span></code></a>, or <a class="link" href="ref/boost__json__string.html" title="string"><code class="computeroutput"><span class="identifier">string</span></code></a>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="ref/boost__json__serializer.html" title="serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>
                </p>
              </td>
<td>
                <p>
                  A stateful object which may be used to efficiently serialize one
                  or more instances of <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>, <a class="link" href="ref/boost__json__array.html" title="array"><code class="computeroutput"><span class="identifier">array</span></code></a>, <a class="link" href="ref/boost__json__object.html" title="object"><code class="computeroutput"><span class="identifier">object</span></code></a>, or <a class="link" href="ref/boost__json__string.html" title="string"><code class="computeroutput"><span class="identifier">string</span></code></a>.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        To facilitate debugging and ease of output, library container types may be
        written to standard output streams using the stream operator:
      </p>
<pre class="programlisting"><span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">5</span> <span class="special">};</span>

<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">jv</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
</pre>
<p>
        The <a class="link" href="ref/boost__json__serialize.html" title="serialize"><code class="computeroutput"><span class="identifier">serialize</span></code></a>
        function converts a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a> into a <a href="https://en.cppreference.com/w/cpp/string/basic_string" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code></a>:
      </p>
<pre class="programlisting"><span class="identifier">value</span> <span class="identifier">jv</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">5</span> <span class="special">};</span>

<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">serialize</span><span class="special">(</span> <span class="identifier">jv</span> <span class="special">);</span>
</pre>
<p>
        In situations where serializing a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a> in its entirety is inefficient
        or even impossible, <a class="link" href="ref/boost__json__serializer.html" title="serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> can be used to incrementally
        serialize a <a class="link" href="ref/boost__json__value.html" title="value"><code class="computeroutput"><span class="identifier">value</span></code></a>
        incrementally. This may be done for a variety of reasons, such as to avoid
        buffering the entire output, or to ensure that a fixed amount of work is
        performed in each cycle. Instances of <a class="link" href="ref/boost__json__serializer.html" title="serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> maintain an output state
        using internal dynamically allocated structures, with an interface to retrieve
        successive buffers of the serialized output into a caller provided buffer.
        Here is an example, demonstrating how <a class="link" href="ref/boost__json__operator_lt__lt_.html" title="operator&lt;&lt;"><code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code></a>
        may be implemented using a <a class="link" href="ref/boost__json__serializer.html" title="serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>:
      </p>
<pre class="programlisting"><span class="comment">// Serialize a value into an output stream</span>

<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span>
<span class="keyword">operator</span><span class="special">&lt;&lt;(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">os</span><span class="special">,</span> <span class="identifier">value</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">jv</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="comment">// Create a serializer</span>
    <span class="identifier">serializer</span> <span class="identifier">sr</span><span class="special">;</span>

    <span class="comment">// Set the serializer up for our value</span>
    <span class="identifier">sr</span><span class="special">.</span><span class="identifier">reset</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">jv</span> <span class="special">);</span>

    <span class="comment">// Loop until all output is produced.</span>
    <span class="keyword">while</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">sr</span><span class="special">.</span><span class="identifier">done</span><span class="special">()</span> <span class="special">)</span>
    <span class="special">{</span>
        <span class="comment">// Use a local buffer to avoid allocation.</span>
        <span class="keyword">char</span> <span class="identifier">buf</span><span class="special">[</span> <span class="identifier">BOOST_JSON_STACK_BUFFER_SIZE</span> <span class="special">];</span>

        <span class="comment">// Fill our buffer with serialized characters and write it to the output stream.</span>
        <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">sr</span><span class="special">.</span><span class="identifier">read</span><span class="special">(</span> <span class="identifier">buf</span> <span class="special">);</span>
    <span class="special">}</span>

    <span class="keyword">return</span> <span class="identifier">os</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        As with the parser, the serializer may be reused by calling <a class="link" href="ref/boost__json__serializer/reset.html" title="serializer::reset"><code class="computeroutput"><span class="identifier">serializer</span><span class="special">::</span><span class="identifier">reset</span></code></a>. This sets up the object to
        serialize a new instance and retains previously allocated memory. This can
        result in performance improvements when multiple variables are serialized.
      </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2019, 2020 Vinnie Falco<br>Copyright © 2020 Krystian Stasiowski<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="allocators/uses_allocator.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
